This PR augments the docs-builder changelog render functionality implemented in #2341
It relates to add_blockers functionality in #2350

Impetus

The need for this functionality arose when I was working on testing the workflow in elasticsearch and elasticsearch-serverless repos (see draft config files in elastic/elasticsearch#140141 and https://github.com/elastic/elasticsearch-serverless/pull/5156). In the case of the elasticsearch repo in particular, there will be changelogs created for PRs that technically apply to and are delivered in both stack and serverless releases (and thus reasonably end up in the bundles if we're generating them based on the official list of PRs in a release or even if we're generating the bundles based on the "products" info in the changelogs). However, the Elasticsearch stakeholders have provided a list of "areas" that should not be included in the serverless release docs (since they're not something users need to care about e.g. ILM, Watcher, monitoring, etc). Right now we're filtering those out via a spreadsheet that keys off the PR labels so we need to be able to continue to do something along that line with this tooling.

After I got the "areas" filtering working, I realized we ought to do the same for "types" since we've added some types (e.g. docs) that we don't have anywhere to publish yet but that would be nice to start collecting changelogs for nonetheless.

NOTE: For now I've commented the changelogs out instead of removing them entirely, so that we can double-check with PMs or stakeholders until we're absolutely confident in the exclusions. In the long term if we want to remove instead of comment, that's fine with me.

Summary

• Adds the render_blockers feature to the changelog configuration system to optionally comment out certain changelog entries from the markdown output

An entry is blocked if:

• Any product in the bundle matches any product key in render_blockers AND
• (Any area in the entry matches OR any type in the entry matches)

NOTE: The products in the render_blockers definition are intentionally matched against the bundle's products rather than against the individual changelogs' products.

Examples

1. Check out the PR and generate the binaries per README.md:

   ./build.sh clean
   ./build.sh publishbinaries
   cd .artifacts/publish/docs-builder/release

2. Create some changelogs with various types and areas, for example:

    ./docs-builder changelog add --pr 108759 --repo elasticsearch --owner elastic \
      --products "elasticsearch" --type bug-fix --areas "autoscaling,Infra/REST API" \
      --output test-1/   --feature-id test-feature
   
   ./docs-builder changelog add --title 'test deprecation' --impact 'Describe the impact' \
     --action 'Describe next steps' --description 'A more detailed description'
     --repo elasticsearch --owner elastic --products "elasticsearch" \
     --type deprecation --areas watcher --output test-1/
   
    ./docs-builder changelog add --title 'test breaking' \
      --description 'A more detailed description' --repo elasticsearch --owner elastic \
      --products "elasticsearch" --type breaking-change --areas search --output test-1/
   
   ./docs-builder changelog add --title 'Awesome new docs were added' \
     --products "elasticsearch" --type docs --areas "search" --output test-1/ \
     --feature-id awesome

3. Create changelog bundles:

   ./docs-builder changelog bundle --all --directory ./test-1 \
     --output-products "elasticsearch 1.2.3" \
     --output ./bundles/changelog-bundle-es.yml
   
   ./docs-builder changelog bundle --all --directory ./test-1 \
     --output-products "cloud-serverless 2026-01-01" \
     --output ./bundles/changelog-bundle-ess.yml

4. Add a changelog configuration file with a render_blockers section. For example, create a changelog.yml file that contains:

    render_blockers:
      # Multiple products (comma-separated) with areas and types that should be blocked
      cloud-serverless:
        areas: # List of area values that should be blocked (commented out) during render
          - Autoscaling
          - Watcher
        types: # List of type values that should be blocked (commented out) during render
          - docs
      # Single product with areas and types that should be blocked
      elasticsearch:
        types:
          - docs

5. Render the serverless bundle and check whether the render_blockers are heeded.

   ./docs-builder changelog render  \
     --config "./changelog.yml" \
     --input "./bundles/changelog-bundle-ess.yml,./test-1,elasticsearch" \
     --output ./out-ess

   This command returns the following warning messages:

   The following errors and warnings were found in the documentation
   
   Warning: Changelog entry 'Awesome new docs were added' will be commented out in markdown output because it matches render_blockers: product 'cloud-serverless' with type 'docs'
   
   Warning: Changelog entry 'test deprecation' will be commented out in markdown output because it matches render_blockers: product 'cloud-serverless' with area 'watcher'
   
   Warning: Changelog entry 'Expose `?master_timeout` in autoscaling APIs' will be commented out in markdown output because it matches render_blockers: product 'cloud-serverless' with area 'autoscaling'
   

6. Render the Elasticsearch bundle but add some feature filtering too:

   ./docs-builder changelog render \
    --config "./changelog.yml" \
    --input "./bundles/changelog-bundle-es.yml,./test-1,elasticsearch" \
    --output ./out-es
    --hide-features awesome,test-feature

   This command generates the following warnings:

   Warning: Changelog entry 'Awesome new docs were added' with feature-id 'awesome' will be commented out in markdown output
   
   Warning: Changelog entry 'Expose `?master_timeout` in autoscaling APIs' with feature-id 'test-feature' will be commented out in markdown output
   
   Warning: Changelog entry 'Awesome new docs were added' will be commented out in markdown output because it matches render_blockers: product 'elasticsearch' with type 'docs'

Changes made

• Configuration Structure (ChangelogConfiguration.cs)
  • Added RenderBlockers property to ChangelogConfiguration as Dictionary<string, RenderBlockersEntry>
  • Added RenderBlockersEntry with Areas and Types properties
  • Keys can be a single product ID or comma-separated product IDs (e.g., "elasticsearch, cloud-serverless")
• Configuration File (changelog.yml.example)
  • Added render_blockers section with commented examples for products and areas
• Render Logic (ChangelogService.cs)
  • Updated LoadChangelogConfiguration to:
    • Default available_types, available_subtypes, and available_lifecycles if not specified
    • Validate render_blockers types against available_types
  • Loads changelog configuration in RenderChangelogs
  • Extracts render_blockers
  • Parses comma-separated product keys
  • Modifies the entry tracking to include bundle product IDs with each entry: (ChangelogData entry, string repo, HashSet<string> bundleProductIds)
  • Updates ShouldBlockEntry to accept HashSet<string> bundleProductIds and check those instead of entry.Products
  • Creates a mapping entryToBundleProducts to track which bundle products belong to each entry
  • Updates all rendering methods (RenderIndexMarkdown, RenderBreakingChangesMarkdown, RenderDeprecationsMarkdown, RenderEntriesByArea) to accept and use the entryToBundleProducts mapping
  • Updates all call sites to pass bundle product IDs when checking if an entry should be blocked
  • The configuration file is now loaded from the specified path (or defaults to docs/changelog.yml)
• Updated ChangelogCommand.cs:
  • Added config parameter to the Render method signature
  • Added XML documentation for the --config parameter
  • Passed the config value to ChangelogRenderInput
• Updated ChangelogRenderInput.cs:
  • Added Config property to store the configuration file path
• Tests (ChangelogServiceTests.cs)
  • Added tests:
    • RenderChangelogs_WithRenderBlockers_CommentsOutMatchingEntries - Tests basic blocking with single product
    • RenderChangelogs_WithRenderBlockers_CommaSeparatedProducts_CommentsOutMatchingEntries - Tests comma-separated product keys
    • RenderChangelogs_WithRenderBlockers_MultipleProductsInEntry_ChecksAllProducts - Tests entries with multiple products
    • RenderChangelogs_WithRenderBlockers_UsesBundleProductsNotEntryProducts to verify that bundle products are used, not entry products
    • RenderChangelogs_WithCustomConfigPath_UsesSpecifiedConfigFile- Tests a config file in a custom location (not in `docs/ subdirectory)
    • Added tests for type blocking
    • Added tests for combined areas and types blocking
    • Added tests to verify default values for available_types, available_subtypes, and available_lifecycles
    • Added test to verify validation of invalid types in render_blockers
• Made LoadChangelogConfiguration internal:
  • Added InternalsVisibleTo attribute to allow test access
• Documentation
  • Updated docs/contribute/changelog.md with the render --config option and a new "Render blockers" section explaining the format
  • Updated docs/cli/release/changelog-render.md with the new option, and a short blurb and link

The implementation follows the same pattern [for commenting out changelog entries] as hideFeatures but checks products, areas, and types from the configuration instead of feature IDs from command-line arguments. When a changelog entry matches any values in render_blockers, it is commented out in the markdown output and a warning is emitted explaining why.

All tests pass and the build succeeds. The feature now supports blocking changelog entries by both areas and types, with proper validation and default handling.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

3. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1 agent